# 의존성 트리 충돌 (Dependency Tree Conflict)

## 1. 개요
**의존성 트리 충돌**이란 소프트웨어 프로젝트가 사용하는 여러 라이브러리들이 서로 다른 버전의 동일한 하위 라이브러리를 요구할 때, 패키지 매니저가 단일 버전을 결정하지 못하거나 호환되지 않는 버전을 선택하여 발생하는 시스템적 불일치 상태를 의미한다.

현대의 소프트웨어 개발은 수많은 외부 라이브러리를 조합하여 이루어지며, 이 과정에서 **다이아몬드 의존성 문제(Diamond Dependency Problem)**가 빈번하게 발생한다.

**[다이아몬드 의존성 구조도]**
```text
       [프로젝트 A]
        /       \
   [라이브러리 B] [라이브러리 C]
        \       /
     [라이브러리 D]
 (B는 v1.0 요구 / C는 v2.0 요구)
```
위 구조처럼 프로젝트 A가 B와 C에 의존하고, B와 C가 각각 동일한 라이브러리 D의 서로 다른 버전에 의존할 때, 최종적으로 프로젝트 A가 어떤 버전의 D를 사용해야 하는지 결정할 수 없는 구조적 모순을 말한다. 이러한 충돌은 빌드 실패뿐만 아니라, 런타임 시 예측 불가능한 오류를 야기하여 시스템의 안정성을 심각하게 저해한다.

## 2. 충돌 발생 원리와 유형

### 2.1 발생 메커니즘
의존성 충돌은 **직접 의존성(Direct Dependency)**과 **간접 의존성(Transitive Dependency)**의 계층 구조에서 발생한다. 개발자가 명시적으로 추가한 라이브러리가 직접 의존성이라면, 그 라이브러리가 작동하기 위해 내부적으로 사용하는 또 다른 라이브러리들이 간접 의존성이 된다. 이 간접 의존성들의 버전 요구사항이 서로 충돌할 때 트리 구조 내에서 버전 불일치가 발생한다.

### 2.2 버전 충돌 유형 비교
버전 충돌의 심각성은 주로 **시맨틱 버저닝(Semantic Versioning, SemVer)** 기준에 따라 결정된다.

| 충돌 유형 | 설명 | 위험도 | 영향 및 결과 |
| :--- | :--- | :---: | :--- |
| **Major 버전 불일치** | 하위 호환성이 깨진 버전 간의 충돌 (예: v1.x ↔ v2.x) | **높음** | API 변경으로 인해 `NoSuchMethodError` 또는 `ClassNotFoundException` 발생 가능성 매우 높음 |
| **Minor 버전 불일치** | 기능 추가는 되었으나 하위 호환성은 유지되는 버전 간 충돌 | **중간** | 최신 기능을 사용하는 코드에서 구버전 라이브러리 로드 시 런타임 오류 발생 가능 |
| **Patch 버전 불일치** | 버그 수정만 포함된 버전 간 충돌 | **낮음** | 대부분의 경우 최신 패치 버전으로 통합 시 문제없이 작동함 |

## 3. 언어 및 도구별 해결 전략

각 언어의 패키지 매니저는 충돌을 해결하기 위해 서로 다른 기본 전략을 채택하고 있다.

### 3.1 도구별 기본 충돌 해결 방식

| 도구 | 주요 언어 | 기본 해결 전략 | 특징 |
| :--- | :--- | :--- | :--- |
| **npm / yarn** | JavaScript | **중복 허용 (Nested)** | `node_modules` 내에 여러 버전의 동일 라이브러리를 계층적으로 설치하여 격리함 |
| **Gradle** | Java/Kotlin | **최신 버전 우선 (Newest)** | 충돌 발생 시 기본적으로 가장 높은 버전의 라이브러리를 선택함 |
| **Maven** | Java | **가까운 버전 우선 (Nearest)** | 의존성 트리 상에서 프로젝트 루트와 가장 가까운(깊이가 얕은) 버전을 선택함 |
| **Pip** | Python | **의존성 리졸버 (Resolver)** | 의존성 리졸버를 통해 설치 전 버전 호환성을 검사하며, 충돌 시 설치를 중단하고 에러를 발생시킴 |

## 4. 수동 해결 방법 및 최적화

자동 해결 전략이 실패하거나, 특정 버전의 라이브러리가 반드시 필요한 경우 개발자가 직접 개입해야 한다.

### 4.1 버전 강제 지정 및 제외
특정 버전을 강제하거나, 문제가 되는 간접 의존성을 트리에서 제거하는 방법이다.

**Gradle (build.gradle)**
```gradle
dependencies {
    implementation('com.example:library-a:1.0') {
        // 특정 간접 의존성 제외
        exclude group: 'org.unwanted', module: 'conflict-lib'
    }
    
    // 특정 버전으로 강제 고정
    constraints {
        implementation('org.unwanted:conflict-lib:2.1.0') {
            because 'version 2.1.0 fixes a critical security vulnerability'
        }
    }
}
```

**npm / Yarn (package.json)**
Yarn의 경우 `resolutions`, npm(v8+)의 경우 `overrides` 필드를 사용하여 하위 의존성 버전을 강제할 수 있다.
```json
{
  "dependencies": {
    "library-a": "1.0.0",
    "library-b": "2.0.0"
  },
  "overrides": {
    "conflict-lib": "2.1.0"
  }
}
```

### 4.2 섀도잉 (Shadowing / Shading)
동일한 라이브러리의 서로 다른 두 버전이 반드시 동시에 필요할 때 사용하는 고급 기법이다. 라이브러리의 패키지 경로(Namespace)를 물리적으로 변경하여 클래스 로더가 서로 다른 클래스로 인식하게 만든다.

**[섀도잉 적용 전후 경로 비교]**
| 구분 | 적용 전 (충돌 발생) | 적용 후 (격리 완료) |
| :--- | :--- | :--- |
| **버전 1.0 경로** | `com.google.gson.Gson` | `shaded.v1.com.google.gson.Gson` |
| **버전 2.0 경로** | `com.google.gson.Gson` | `shaded.v2.com.google.gson.Gson` |

단, 섀도잉은 런타임 시 동일 라이브러리가 여러 번 로드되어 메모리 사용량이 증가하며, 서로 다른 패키지 경로의 동일 클래스 간에는 형변환(Type Casting)이 불가능하다는 치명적인 부작용이 있으므로 주의하여 사용해야 한다.

## 5. 충돌 진단 및 실례

### 5.1 충돌 진단 도구 및 명령어
충돌을 해결하기 전, 현재의 의존성 트리를 시각화하여 분석하는 것이 필수적이다.

- **npm**: `npm list` 또는 `npm explain <package-name>`
- **Gradle**: `./gradlew dependencies`
- **Maven**: `mvn dependency:tree`
- **Pip**: `pip check` (기본), `pipdeptree` (외부 라이브러리 설치 필요)

### 5.2 런타임 충돌 증상
빌드 단계에서 에러가 나지 않더라도, 런타임(실행 중)에 다음과 같은 증상이 나타나면 의존성 충돌을 의심해야 한다.
- **`NoSuchMethodError`**: 컴파일 시에는 존재했던 메서드가 실행 시점에 로드된 라이브러리 버전이 낮아 찾을 수 없는 경우.
- **`ClassNotFoundException` / `NoClassDefFoundError`**: 특정 버전에서 삭제된 클래스를 참조하려 할 때 발생.
- **예측 불가능한 동작**: 동일한 입력값에 대해 라이브러리 버전별 내부 로직 차이로 인해 결과값이 달라지는 현상.

### 5.3 실제 사례 및 해결 시나리오
**[시나리오]**
- 프로젝트 P가 `Logging-Lib v1.0`과 `Network-Lib v2.0`을 사용함.
- `Logging-Lib v1.0`은 내부적으로 `Common-Utils v1.0`을 요구함.
- `Network-Lib v2.0`은 내부적으로 `Common-Utils v2.0`을 요구함.
- **결과**: Maven 환경에서 `Common-Utils v1.0`이 먼저 선언되어 로드됨 $\rightarrow$ `Network-Lib` 실행 중 `Common-Utils v2.0`에만 존재하는 메서드를 호출하려다 `NoSuchMethodError` 발생.

**[해결 과정]**
1. `mvn dependency:tree`를 통해 `Common-Utils`가 중복으로 정의되어 있음을 확인.
2. `Common-Utils v2.0`이 v1.0의 하위 호환성을 유지하는지 확인.
3. `pom.xml`의 `<dependencyManagement>` 섹션에 `Common-Utils v2.0`을 명시하여 프로젝트 전체에서 v2.0을 사용하도록 강제함.

## 6. 충돌 방지를 위한 모범 사례

1. **시맨틱 버저닝(SemVer) 준수**: 라이브러리 배포 시 `Major.Minor.Patch` 규칙을 엄격히 지켜 사용자에게 변경 영향도를 명확히 알린다.
2. **최소 의존성 원칙**: 불필요한 외부 라이브러리 도입을 지양하고, 가급적 표준 라이브러리를 활용하여 의존성 트리의 깊이를 낮춘다.
3. **락 파일(Lock file) 활용**: `package-lock.json`, `poetry.lock`, `Gemfile.lock` 등을 버전 관리 시스템(Git)에 포함시켜 모든 개발자와 서버 환경에서 동일한 의존성 트리를 유지한다.
4. **정기적인 의존성 업데이트**: 버전 격차가 너무 커지면 나중에 업데이트할 때 충돌 해결 비용이 기하급수적으로 증가하므로, 소규모 업데이트를 자주 수행한다.